fix(types): accept an explicit undefined wherever a consumer writes an optional member - #418

Problem

React Native declares its own optional props as ?: T | undefined, while the props this package adds are bare ?: string. Under exactOptionalPropertyTypes the two differ, and the difference falls on the most ordinary thing a consumer writes:

<View className={condition ? "p-4" : undefined} />

error TS2769: No overload matches this call.
  Overload 1 of 2, '(props: ViewProps): View', gave the following error.
    Type '{ className: string | undefined; }' is not assignable to type 'Readonly<ViewProps>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.

styled() has the same bare members: the className its unmapped overload adds, passThrough, and a mapping's nativeStyleMapping; so do the options a consumer writes for the compiler, Metro, the jest helper and useNativeCss. A consumer's own declaration that widens such a prop takes effect only when it comes before this package's in the program.

A mapping entry left undefined is also a runtime error: mappingToConfig keeps it, and nativeStyleMapping calls path.split(".") on it:

const StyledView = styled(View, {
  className: {
    target: "style",
    nativeStyleMapping: { color: "accessibilityLabel", backgroundColor: undefined },
  },
});

// .subject { color: blue; background-color: red; }
// The render throws "Cannot read properties of undefined (reading 'split')",
// and the render React retries has no backgroundColor.
<StyledView className="subject" />;

Solution

• Every optional member of types.d.ts and runtime.types.ts, and of the compiler's, Metro's, the jest helper's and useNativeCss's options, takes | undefined, as React Native writes its own, except InlineStyleRecord's s?: never, which marks a key that must stay absent. The jest helper's options leave out logger, which the helper always sets itself.
• The props a styled() mapping adds come from one StyledSourceProps type, which StyledProps, StyledReactElement and StyledComponent use, and which the unmapped overload uses with DefaultStyledConfiguration, the default mapping src/native/api.tsx and src/web/api.tsx both pass. They stay writable, as the component's own props are.
• A mapping's keys are the style keys the compiler collects: React Native's, which an editor completes, or the camel-cased name of a -rn- declaration, so any string is a key. The type no longer resolves the mapping's target, and an entry may be left undefined, which mappingToConfig drops.

Tests

• src/__tests__/types/optional-members.test.ts checks both declaration files and the option types with the type checker, the flag on, and fails on any optional member that rejects undefined. A type that resolves is read member by member, inherited, picked and mapped members included, down to the option types its members reach; a generic one is read as written, a mapped type over keyof T and a library type such as Partial over a type parameter among its forms. A listed type the file no longer declares fails the test. Its fixture holds each form, beside the ones that pass. Against main it reports 49 members, an inherited one under each type that inherits it; here none.
• src/__tests__/native/_styled-types.tsx: a mapping takes any style key, a -rn- declaration's among them, and an entry left undefined, rejects a value naming no prop, and the class props stay writable; on main tsc fails the undefined entry and the writable mapped prop.
• src/__tests__/types/styled.test.ts: the editor completes React Native's style keys whatever the target; it fails on main.
• src/__tests__/native/styled.test.ios.tsx: a mapping entry set to undefined maps nothing. On main the case fails tsc, and its render throws.

Verification

Every ci.yml job passes on this head merged into main with #477's harness fix: lint, typecheck, the tests (1350 passed), both builds, the web export, nothing unstaged, commitlint, and the iOS dev build on macOS 27.0.1 with Xcode 27.0, where CI pins 26.6.

A styled() mapping now costs the type checker about 8,100 instantiations against 35,200 on main, and tsc --noEmit over this repository makes 930,621 type instantiations against 979,442. The runs, and the snippet above on main and on this branch, are in this comment.

Known limits

• A misspelled mapping key compiles, since a -rn- declaration can add any key to the style.
• styled() over Reanimated's animated components still exceeds the type checker's depth (TS2589, TS2590), as on main, at about 15% fewer instantiations.
• The package's own code has 11 errors under the flag, in six files; this PR's widening of CompilerOptions.logger and Config.nativeStyleMapping clears the 6 others main has.

Merge order

• fix(native): answer :dir() per element, and compile every spelling of it #459 adds dir?: "ltr" | "rtl" to ViewProps and TextProps, and feat(metro): surface compiler warnings during a build #430 and fix(compiler): recover from a rule lightningcss cannot parse #493 add warnings?: WarningLevel to Metro's options. Whichever lands second widens them, and optional-members.test.ts fails until it does.
• fix: avoid walking ref props in styled mappings #344 rewrites the same nativeStyleMapping declaration in src/runtime.types.ts.